/*----------------------------------------------------------------------------
The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in
compliance with the License. You may obtain a copy of the 
License at http://www.mozilla.org/MPL/
	
Software distributed under the License is distributed on 
an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, 
either express or implied. 
See the License for the specific language governing rights and 
limitations under the License.
	
The Original Code is Fever RS ( ActionScript 3 ) Framework code.
	
The Initial Developer of the Original Code is Romain Ecarnot.
Portions created by Initial Developer are Copyright (C) 2006
the Initial Developer. All Rights Reserved.
	
Contributor(s):
	
Unless required by applicable law or agreed to in writing, 
software distributed under the License is distributed on 
an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 
OF ANY KIND, either express or implied.
See the License for the specific language governing permissions 
and limitations under the License.
----------------------------------------------------------------------------*/

package fever.ui.menu 
{
	import flash.events.ContextMenuEvent;
	import flash.ui.ContextMenu;
	
	import com.bourre.collection.HashMap;
	import com.bourre.core.HashCodeFactory;
	import com.bourre.events.EventBroadcaster;
	
	import fever.events.PopupContextMenuEvent;
	import fever.log.FeverDebug;
	import fever.ui.menu.PopupContextMenuLocator;
	import fever.utils.Stringifier;	

	/**
	 * Dispatched when a user first generates a context menu but before 
	 * the contents of the context menu are displayed.
	 * 
	 * <p>This allows your program to modify the set of context menu items 
	 * before displaying the menu.<br />
	 * The user generates the context menu by right-clicking the pointing 
	 * device.</p>
	 * 
	 * @eventType fever.events.PopupContextMenuEvent.onContextMenuSelectEVENT
	 */
	[Event(name="onContextMenuSelect", type="fever.events.PopupContextMenuEvent")]
	
	
	/**
	 * The ContextMenu class provides control over the items in the Flash 
	 * Player context menu.
	 * 
	 * <p>Users open the context menu by right-clicking (Windows) or 
	 * Control-clicking (Macintosh) Flash Player.<br />
	 * You can use the methods and properties of the PopupContextMenu 
	 * class to add custom menu items, control the display of 
	 * the built-in context menu items (for example, Zoom In and Print), 
	 * or create copies of menus.</p>
	 * 
	 * @includeExample PopupContextMenuSample.as -noswf
	 * 
	 * @see fever.ui.menu.PopupContextMenuItem	 * @see fever.ui.menu.PopupContextMenuLocator
	 * 
	 * @author Romain Ecarnot
	 */
	public class PopupContextMenu extends EventBroadcaster
	{
		//--------------------------------------------------------------------
		// Private properties
		//--------------------------------------------------------------------
		
		private var _items : HashMap;		private var _menu : ContextMenu;		
		
		//--------------------------------------------------------------------
		// Private properties
		//--------------------------------------------------------------------
		
		private var _menuID : String;
		
		
		//--------------------------------------------------------------------
		// Public properties
		//--------------------------------------------------------------------
		
		/**
		 * Returns menu identifier.
		 * 
		 * <p>Used by PopupContextMenuLocator manager.</p>
		 * 
		 * @see fever.ui.menu.PopupContextMenuLocator
		 */
		public function get id() : String { return _menuID; }
		
				
		//--------------------------------------------------------------------
		// Public API
		//--------------------------------------------------------------------
		
		/**
		 * Constructor.
		 * 
		 * @param menuID Context menu registration identifier 
		 * used in <code>PopupContextMenuLocator</code> manager
		 * 
		 * @see fever.ui.menu.PopupContextMenuLocator
		 */
		public function PopupContextMenu( menuID : String = null )
		{
			super( this );
			
			if( menuID == null || PopupContextMenuLocator.isRegistred( menuID ) ) 
				menuID = "__cm__" +	HashCodeFactory.getNextKey( );
			
			_menuID = menuID;
			_menu = new ContextMenu( );
			_menu.addEventListener( 
				ContextMenuEvent.MENU_SELECT, 
				_onMenuSelect 
			);
			
			_items = new HashMap( );
			
			hideBuiltInItems();
			
			PopupContextMenuLocator.register( this, _menuID );
		}
		
		/**
		 * Returns Flash ContextMenu object
		 */
		public function getFlashMenu() : ContextMenu
		{ 
			return _buildContextMenu(); 
		}
		
		/**
		 * Builds and adds new <code>PopupContextMenuItem</code> using 
		 * passing arguments. 
		 * 
		 * @param caption Item caption
		 * @param id Registration item id
		 * 
		 * @return PopupContextMenuItem instance
		 * 
		 * @see fever.ui.menu.PopupContextMenuItem
		 */
		public function addItem( caption : String, id : String = null ) 
			: PopupContextMenuItem
		{
			if( id == null )
			{
				id = "_ct_" + HashCodeFactory.getNextKey();
			}
			
			if( !_items.containsKey( id ) ) 
			{
				var item : PopupContextMenuItem = 
					PopupContextMenuItem.create( caption, id, _menuID );
				_items.put( id, item );
				
				_buildContextMenu();
				
				return item;
			}
			
			return null;
		}
		
		/**
		 * Removes <code>PopupContextMenuItem</code> instance registred 
		 * with <code>id</code> from context menu.
		 * 
		 * @param id item's id to remove
		 * 
		 * @return Removed <code>PopupContextMenuItem</code> instance
		 * 
		 * @see fever.ui.menu.PopupContextMenuItem
		 */
		public function remove( id : String ) : PopupContextMenuItem
		{
			var result : PopupContextMenuItem = _items.remove( id ) as PopupContextMenuItem;
			
			_buildContextMenu();
			
			return result;
		}

		/**
		 * Returns <code>PopupContextMenuItem</code> instance registred 
		 * with <code>id</code> in context menu.
		 * 
		 * @param id Item's id to return
		 * 
		 * @return <code>PopupContextMenuItem</code> instance
		 * 
		 * @see fever.ui.menu.PopupContextMenuItem
		 */
		public function getItem( id : String ) : PopupContextMenuItem
		{
			if( _items.containsKey( id ) )
			{
				return 	_items.get( id ) as PopupContextMenuItem;
			}
			else
			{
				FeverDebug.ERROR( "No such item identifier [ " + id + " ]" );
				return null;	
			}
		}
		
		/**
		 * Hides (or not) builtin menu item.
		 */
		public function hideBuiltInItems( visible : Boolean = true ) : void
		{
			if( visible )
			{
				_menu.hideBuiltInItems();
			}
			else
			{
				for( var item : String in _menu.builtInItems )
				{
	    			_menu.builtInItems[item].visible = true;
				}		
			}
		}
		
		/**
		 * Returns <code>true</code> if an <code>PopupContextMenuItem</code> 
		 * is registred using <code>id</code> identifier.
		 */
		public function isRegistred( id : String ) : Boolean
		{
			return 	_items.containsKey( id );
		}
		
		/**
		 * Removes all context menu items.
		 */
		public function release() : void
		{
			removeAllListeners();
			
			_items.clear();
		}
		
		/**
		 * Returns string representation.
		 */
		override public function toString() : String
		{
			return Stringifier.parse( this );
		}
		
		
		//--------------------------------------------------------------------
		// Private implementations
		//--------------------------------------------------------------------
		
		private function _buildContextMenu() : ContextMenu
		{
			_menu.customItems = new Array();
			
			var values : Array = _items.getValues();
			var l : int = values.length;
			
			for( var i : int = 0; i < l; i += 1 )
			{
				_menu.customItems.push( 
					( values[i] as PopupContextMenuItem ).getFlashItem() 
				);
			}
			
			return _menu;
		}
		
		private function _onMenuSelect( event : ContextMenuEvent  ) : void
		{
			var e : PopupContextMenuEvent = new PopupContextMenuEvent( 
					PopupContextMenuEvent.onContextMenuSelectEVENT, 
					this 
				);
			
			broadcastEvent( e );
		}
	}
}